---
title: SAIF.Services.Printing architecture
summary: Architectural responsibilities, boundaries, and interaction patterns.
status: draft
owner: SAIF Documentation
last_reviewed: 2026-08-21
library: SAIF.Services.Printing
reference_type: embedded
---

# SAIF.Services.Printing architecture

`SAIF.Services.Printing` is an infrastructure/service-gateway class library that wraps the xPression document
composition SOAP service (`xpresso.clsGenerate`) and the SQL Server Reporting Services `ReportExecution2005`
SOAP service, adds an asynchronous MSMQ distribution channel that carries an OnBase imaging index payload, and
provides a small `Reporting` framework (`IReport` / `ReportBase` / `XDesignXDocument` / `XDesignXElement`) for
building xPression-format XML documents and driving them through preview, print, distribute, and save flows. It
sits below the application/presentation layers and performs no database access, persistence, or business-object
logic of its own.

## Responsibilities
- Resolve xPression and SSRS endpoint URLs, MSMQ queue paths, and the imaging drop path through the SAIF
  Environment API (`EnvironmentServiceBase`), never from `ConfigurationManager.AppSettings`.
- Provide `clsPrint` as the protocol/transport gateway for xPression: request assembly, synchronous-versus-queued
  dispatch (`Asynchronous`), and MSMQ transaction lifecycle (`StartMQTransaction` / `EndMQTransaction`).
- Provide `clsRSPrint` as the protocol gateway for SSRS: report path, parameters, format/extension mapping, and
  rendering.
- Provide the `Reporting` framework (`IReport` / `ReportBase`) to orchestrate a report lifecycle
  (`Create` → `Render` → `Print` / `Distribute` / `Save`) and to accumulate non-throwing `ErrorDetail` entries.
- Serialize xPression-aware `XDocument`/`XElement` subclasses (`XDesignXDocument`, `XDesignXElement`) into the
  xPression XML dialect, including key propagation for nested repeating sections (`BR-PRT-016`).

## Component boundaries
- `clsPrint`: xPression protocol/transport concern — endpoint resolution, request assembly, sync-vs-queued
  dispatch, and MSMQ transaction handling. Depends on `SAIF.Services.Imaging.Import.clsImageImport` as the
  imaging index payload type carried on `ImportInfo` and `CompositeRequestClass.Importinfo`.
- `clsRSPrint`: SSRS protocol concern — report path, parameters, format/extension mapping, render. Its injecting
  constructor is `Private`, so it is reachable only through the ambient `AppGlobal.EnvironmentService`, unlike
  `clsPrint`'s public injecting constructor.*
- `Reporting.*` (`IReport`, `ReportBase`, `XDesignXDocument`, `XDesignXElement`, `ErrorDetail`): content concern —
  builds the xPression data document, serializes it to the xPression dialect, and drives the report lifecycle.
  `ReportBase` is `MustInherit`; no concrete subclass exists in this repository's built projects (the only sample,
  in the excluded test project, is not part of the solution).*
- Generated proxy namespaces `SAIF.Services.Printing.xpresso` and `SAIF.Services.Printing.SharepointReporting`:
  SOAP client boundary to the external xPression and SSRS services respectively; not hand-written.

## Interaction model
- Callers in the presentation/application layer (`LegalMaintenance/frmPrintPreview.aspx.vb`,
  `SAIF.Business.View.Policy/clsPayrollClassInfoCollection.vb`) construct `clsPrint`, `clsRSPrint`, or a
  `ReportBase` subclass and invoke preview/print/distribute/save operations directly; there is no mediating
  business-object or persistence layer inside this library.
- `clsPrint.distributeDocument` fans out to either a transactional MSMQ send (`CompositeRequestClass` serialized
  with `BinaryMessageFormatter`) or a direct synchronous SOAP call to xPression, selected by the `Asynchronous`
  flag (`BR-PRT-003`).
- `ReportBase.Render` resolves the caller's default printer through `clsSecurityPrincipal`, selecting the Web or
  Windows platform based on `EnvironmentServiceBase.IsWeb` (`BR-PRT-009`), then delegates rendering to the
  report's `clsPrint` instance — created with the parameterless constructor, so the environment service the
  report itself received is not propagated to it.*
- Both `clsPrint` and `clsRSPrint` expose a parameterless constructor that reaches the ambient static
  `AppGlobal.EnvironmentService`, coupling instance creation to process-wide state rather than pure
  dependency injection.*

## Architecture diagram
The following diagram shows the high-level component interactions between the presentation layer, this
library's protocol gateways and reporting framework, and the external document/report services.

```mermaid
flowchart TD
	Caller["Presentation/business callers<br>(frmPrintPreview, clsPayrollClassInfoCollection)"] --> ReportBase["ReportBase / IReport<br>(report lifecycle)"]
	Caller --> ClsPrint["clsPrint<br>(xPression gateway)"]
	ReportBase --> XDesign["XDesignXDocument / XDesignXElement<br>(xPression XML builder)"]
	ReportBase --> ClsPrint
	ClsPrint --> ImageImport["SAIF.Services.Imaging.Import<br>clsImageImport"]
	ClsPrint --> MSMQ["MSMQ transactional queue<br>(documentMSMQPath)"]
	ClsPrint --> Xpresso["xPression clsGenerate<br>(SOAP)"]
	ClsRSPrint["clsRSPrint<br>(SSRS gateway)"] --> SSRS["ReportExecution2005<br>(SOAP)"]
	Caller --> ClsRSPrint
	ClsPrint --> EnvApi["EnvironmentServiceBase / AppGlobal<br>(SAIF Environment API)"]
	ClsRSPrint --> EnvApi
	ReportBase --> EnvApi
```

## Sequence diagram
The following diagram shows the primary distribute-document sequence through `clsPrint`, including the
MSMQ-versus-direct dispatch decision.

```mermaid
sequenceDiagram
	participant Client
	participant ClsPrint as clsPrint
	participant MSMQ as MSMQ queue
	participant Xpresso as xPression clsGenerate
	Client->>ClsPrint: distributeDocument(package, xml)
	alt Asynchronous = True
		ClsPrint->>ClsPrint: StartMQTransaction
		ClsPrint->>MSMQ: Send CompositeRequestClass (BinaryMessageFormatter)
		ClsPrint->>ClsPrint: EndMQTransaction(True)
	else Asynchronous = False
		ClsPrint->>Xpresso: distributeDocument(package, xml, ImportInfo.ToString, PaperTray.Tray2)
		Xpresso-->>ClsPrint: result
	end
	ClsPrint-->>Client: True
```

## Design constraints
- All environment-specific configuration (endpoint URLs, MSMQ path, IDM path) is retrieved exclusively through
  `EnvironmentServiceBase`; there is no `ConfigurationManager.AppSettings` usage in code.
- `clsRSPrint`'s parameterised constructor is `Private`, so the environment service cannot be substituted from
  outside — only the ambient `AppGlobal.EnvironmentService` path is reachable.*
- The library performs no database access; the `Oracle.ManagedDataAccess` package is referenced only to satisfy
  the framework/runtime `DbProviderFactories` registration and is not exercised by any code here.
- `ReportBase.xPrint` constructs its `clsPrint` with the parameterless constructor, so an injected environment
  service on the report is not propagated to the printer it uses.*
- `IDMEnvs` and `ReportBase.XpressoEnvironment` are declared but not consumed by any logic in this library.**

## Related documentation
- [Index](index.md)
- [Overview](overview.md)
- [Dependencies](dependencies.md)
- [Operations and processes](operations-processes.md)
- [Business rules](business-rules.md)
- [API reference](api/index.md)
- [SAIF.Services.Imaging.Import](../saif-services-imaging-import/overview.md)

> **Note:** Statements marked with * were inferred from code structure, naming conventions, or
> contextual evidence where direct confirmation was not available in source artifacts. Statements
> marked with ** could not be confirmed; treat as unknown until verified.

## Sources
- `SAIF.Services.Printing/clsPrint.vb`
- `SAIF.Services.Printing/clsRSPrint.vb`
- `SAIF.Services.Printing/Reporting/IReport.vb`
- `SAIF.Services.Printing/Reporting/ReportBase.vb`
- `SAIF.Services.Printing/Reporting/XDesignXDocument.vb`
- `SAIF.Services.Printing/Reporting/XDesignXElement.vb`
- `SAIF.Services.Printing/app.config`
- `SAIF.Services.Printing/Web.config`
- `SAIF.Services.Printing/My Project/Settings.Designer.vb`
- `SAIF.Services.Printing/My Project/Settings.settings`
- SAIF.Services.Printing/clsPrint.vb
- SAIF.Services.Printing/clsRSPrint.vb
- SAIF.Services.Printing/Reporting/IReport.vb
- SAIF.Services.Printing/Reporting/ReportBase.vb
- SAIF.Services.Printing/Reporting/XDesignXDocument.vb
- SAIF.Services.Printing/Reporting/XDesignXElement.vb
- SAIF.Services.Printing/Reporting/ErrorDetail.vb